Cream of the Crop 12

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 12 / Cream of the Crop 12 (Part II) / Cream of the Crop 12 (Part II).iso / BBS / IEMSI002.ZIP / IEMSI.DOC < prev next >

Wrap

Text File | 1996-01-18 | 17.7 KB | 398 lines

Documentation for the Interactive Electronic Mail Standard Identification (IEMSI) "include" file (January 1996 Release) for Maximus 3. Included in this file: I. Introduction. II. Setting up the IEMSI.MH file. III. The IEMSI.MH functions and structures. IV. How IEMSI works. I. Introduction. IEMSI is an automated information exchange protocol where the remote and server learn the name, location, and terminal settings of one another so the user doesn't have to manually set his/her settings in the BBS's Change Setup menu. The included IEMSI.MH file was written in Maximus' MEX programming language and brings Maximus 3 Sysops the option of having it. Please freely distribute the IEMSI.MH include file, along with this one (IEMSI.DOC) as much as you want. You may edit it to your liking, but I ask that you not distribute any of those edited copies for two reasons: 1) People might have a problem with the file, and will ask me why it doesn't work. I won't be able to help them if the file has been edited (usually the cause of a problem is the result of an edit). 2) The people that helped me out were noted, and I believe them and myself deserve credit for the file, and not a person that decides to take that information out of the file, and replace it with his/her name. You may contact me by Fidonet Netmail at 1:215/9874, or the Internet at Made.In.USA@yuronet.cmnsens.fidonet.org for problems, questions, or (dare I say it?) compliments. Both BETTER.MEX and SIMPLE.MEX (included with this archive) will run under the DOS version of Maximus 3 without a problem. Please review section two for implementing information, and section three for advanced programming information. II. Setting up the IEMSI.MH file. 1. Copy the files from the archive into your \Max\M directory. 2. Open the IEMSI.MH file with an editor of your choice. 3. Move the cursor to line 28 and follow the set up directions in the file. If you plan to use the included BETTER.MEX or SIMPLE.MEX for a login program, it's recommended that you comment out the '#define DO_EXTRA' line since these MEX programs won't use the extra features. It will reduce the time needed for the program to run. 4. Save and close the file. 5. Use one of the provided MEX programs for your logins, or make your own program. If you use the BETTER.MEX, be sure to edit its define lines (instructions can be found in the file). SIMPLE.MEX doesn't require any editing for use. If you wish to make your own login MEX program, see section III. If there are special instructions for setting up the programs that come with this archive, they will be found at the beginning of the file. 6. Compile the MEX program using the MEX(P) command: DOS> MEX BETTER.MEX OS2> MEXP BETTER.MEX 7. Open your LOGO.MEC file, and place the following line at the end of the file (assuming you are using the original LOGO.MEC): [MEX]d:\path\BETTER.VM Where d: is the drive, path is the path to the file (usually \max\m), and BETTER.MEX is the name of the program you are using for IEMSI logins (either SIMPLE.MEX, BETTER.MEX, or a program you made yourself). Or, you can run only the MEX program to log a user in (bypassing the LOGO.MEC file) by opening your MAX.CTL file and changing the following line: Uses Logo Misc\Logo to: Uses Logo :M\BETTER.VM Don't forget to run SILT(P) if you change your MAX.CTL file. 8. Compile your LOGO.MEC file using the MECCA(P) command from your \Max directory: DOS> MECCA MISC\LOGO OS2> MECCAP MISC\LOGO 9. That's it. Users that have the IEMSI capability should be able to log into your BBS automatically. If you want to have the MEX program automatically update the user's configuration, you will have to make your own MEX program using the usercreate(), userupdate(), userfindopen(), and userfindclose() functions. In this case, you need information about the variables in the _emsi_data structure (see section III below). III. The IEMSI.MH functions and structures. All of the functions useful to any programmer are listed below. There ARE other functions in the file, but they are needed only for the IEMSI process. Note that some of these functions require that others be prototyped also in order to properly function. struct _emsi_data Description This structure contains all the information received from the remote. It describes who, where, and how to contact the person, the remote's terminal capabilities, what the user wants and doesn't want during the login process, and the terminal software the remote is using. Notes If protocols.directzap and/or protocols.zedzap are found TRUE, and you don't have those external protocols installed, have your program interpret them as the Zmodem protocol. If Kermit is found TRUE, and you don't have an external protocol program installed for it, you will need to use another protocol that is found TRUE, prompt the user about which protocol to use, or have a default protocol of none set instead. The different types of variables include strings (string), unsigned characters (uns char), and singed longs (sin long). Field Type Description ------------------------- -------- -------------------------------------------- name string The user's name. The first letter of each word is capitalized. (e.g. "Yuri Wiitala") alias string The user's alias. The first letter of each word is capitalized. (e.g. "Made In Usa") location string The user's location. (e.g. "Pleasanton, CA") data_number string The user's data phone number, if any. Some terminal programs put the voice number here by mistake. (e.g. "(510) 555-1212") voice_number string The user's voice phone number. (e.g. "(510) 555-1212") password string Case insensitive; all letters are made lowercase. (e.g. "secret") birthdate; sin long User's birthday in UNIX notation (seconds elapsed since Jan 1, 1970). Use long_to_stamp() function to convert to a useful date. (e.g. "788940000") This can be a negative number if the user was born before Jan 1, 1970. The following are only available if the '#define DO_EXTRA' line is NOT commented: Field Type Description ------------------------- -------- -------------------------------------------- soft_name string The user's terminal emulation program. (e.g. "Zap-O-Comm") ver string Version of the user's terminal emulation program. (e.g. "2.052") serial string Serial number of the user's terminal emulation program. (e.g. "4A-24E7CB-4C3") crtdef.tty uns char TRUE if TTY terminal emulation is supported. crtdef.avatar uns char TRUE if AVATAR/0+ and ANSI X3.64 are supported. crtdef.ansi uns char TRUE if only ANSI X3.64 is supported. crtdef.vt52 uns char TRUE if DEC VT52 is supported. crtdef.vt100 uns char TRUE if DEC VT100 is supported. VT100 is compatible with ANSI codes, but it will not display color on the user's end. crtdef.len uns char The length of the user's screen in rows. crtdef.width uns char The width of the user's screen (num of chars). crtdef.nulls uns char The number of nulls required. protocols.directzap uns char TRUE if the user can use the DirectZAP file transfer protocol. (a variant of ZedZAP) protocols.zedzap uns char TRUE if the user can use the ZedZap file transfer protocol. (a Zmodem variant) protocols.zmodem uns char TRUE if the user supports Zmodem. (1024 byte data packets) protocols.sealink uns char TRUE if the user supports SEAlink. protocols.kermit uns char TRUE if the user supports Kermit. capabilities.tabs uns char TRUE if the user's terminal software can handle TAB (ASCII 09H) characters. capabilities.ibmchars uns char TRUE if the user's terminal software can handle 8-bit IBM PC ASCII characters. requests.news uns char TRUE if the user wants to have bulletins, announcements, etc., displayed. requests.mailcheck uns char TRUE if the user wants to check for new mail. requests.hotkeys uns char TRUE is the user wants to use hotkeys. requests.scrnclr uns char TRUE if the user wants screen clearing codes to be sent. requests.nopage uns char TRUE if the user is not available for chat (paging disabled). requests.more uns char TRUE if a more prompt should be sent after a screen of information. requests.fullscred uns char TRUE if the full screen message editor/reader should be enabled. capitalize() Prototype string capitalize(string: wrongcase) Arguments wrongcase A string containing any mixture of cases. Return Val. The same string with proper capitalization. Description The first letter of each word of the given string is capitalized, and the remaining letters of each word are changed to lowercase. This function is useful for properly capitalizing names in situations where you cannot be sure that proper capitalization has been used. crc_32_tab() Prototype unsigned long crc_32_tab(unsigned long: index); Arguments index An unsinged long from 0 to 255, which is the index of the crc_32_tab array to be returned. Return Val. The calculated value from the crc_32_tab array at the given index. Description Instead of using the famous crc_32_tab table, used in CRC calculations, this function calculates what the variable at "index" would contain. Calculating rather than using the table shortens the amount of code in the program, and the resources required for the program to run. NOTE: This function will only be available if DO_CRC32 is defined. crc32() Prototype string crc32(string: strtoproc); Arguments strtoproc The string to calculate the Cycle Redundancy Check on. Return Val. The calculated CRC of the given string. Description This function takes the given string and calculates a Cycle Redundancy Check (CRC) on it. A CRC helps two programs make sure that data being transmitted over a modem is 100% error free. NOTE: This function will only be available if DO_CRC32 is defined. hexstrtolong() Prototype signed long hexstrtolong(string: strtoproc); Arguments strtoproc The string containing the hexadecimal number to be converted to decimal. Return Val. The hex number converted to decimal. Description This function takes a string containing a hexadecimal number and converts it to a signed long in decimal. iemsi_detect() Prototype signed int iemsi_detect(ref struct _emsi_data: recvdinfo); Arguments recvdinfo The _emsi_data structure. When the function is complete, this structure will be filled with the user's information if an IEMSI login was successful. Return Val. -2, if a non-IEMSI response was received. -1, if the ICI packet could not be received from the remote properly. 0, if there was no response to the EMSI_IRQ. 1, if the user's information was retrieved successfully from the remote, but the remote couldn't receive the ISI packet successfully. 2 = The IEMSI negotiation was 100% successful. If the returned value is greater than zero, the structure will be filled with the user's information. If the value is less than zero, assume that the user does not support IEMSI logins, his/her software does not conform to 100% of the IEMSI specifications, or the connection between the BBS and the user is very faulty (information cannot be exchanged without error). Description This functions performs an IEMSI negotiation, and if the user supports IEMSI logins, will get the information needed, and will send the user information about the BBS. It takes only one second to determine if the user supports IEMSI, so it will not be noticeable to a user that does not support it. longtohexstr() Prototype string longtohexstr(unsigned long: numtoproc); Arguments numtoproc The number of type unsigned long to convert to hex. Return Val. The eight character string containing the number converted to hex. If the number is not large enough to take up all eight digits, zeros are added in front of the number. Description This function takes a number of type unsinged long (in decimal), and converts it to an eight character string containing the hex equivalent. NOTE: This function will only be available if DO_CRC32 is defined. status_message() Prototype void status_message(string: statmsg); Arguments statmsg The string to print to the local screen about the IEMSI connection. Return Val. No value will be returned since the function is of 'void' type. Description This function will print a status message to only the local screen about the current progress with the IEMSI negotiation. toupper() Prototype unsigned char toupper(unsigned char: letter); Arguments letter The letter to be converted to upperase. Return Val. The letter capitalized. Description This function takes a lowercase letter and makes it uppercase. If the letter is already upperase, or the character given is not a letter at all, the given character will be returned. xor32() Prototype unsigned long xor32(unsigned long: compare1, unsigned long: compare2) Arguments compare1 One of the two values to be compared by the "exclusive or" process. It is of type unsigned long. compare2 The other value to be compared, also an unsigned long. Return Val. The result of the "exclusive or" operation in an unsigned long. Description This function performs an "exclusive or" on the bits of two unsigned long numbers. This process compares the corresponding bits of each number and returns the following according to the following: 1 and 1 ──> 0 1 and 0 ──> 1 0 and 1 ──> 1 0 and 0 ──> 0 NOTE: This function will only be available if DO_CRC32 is defined. IV. How IEMSI works. The IEMSI information exchange starts with the server (BBS) sending the EMSI_IRQ packet. This packet never changes, and is "**EMSI_IRQ8E08." If the remote is IEMSI capable, it should then send its EMSI_ICI packet. This packet contains the "**EMSI_ICI" string, the length of the ICI packet in hex, the actual packet data, and then a 32-bit Cycle Redundancy Check (CRC). Since this packet could contain any kind of data, the CRC is necessary to ensure everything it contains is error-free. If the packet is found to be okay, the server sends its EMSI_ISI packet to the remote. If not, the EMSI_NAK packet is sent to let the remote know that the EMSI_ICI packet needs to be resent. The EMSI_ISI packet contains the "**EMSI_ISI" string, the length of the ISI packet in hex, the packet data (containing the BBS information), and the CRC in hex. If the remote deems the EMSI_ISI packet to be correct, the EMSI_ACK packet is sent back twice. If not, the EMSI_NAK packet is sent, and the server should send the EMSI_ISI packet again. At any time during this process, if either side sends an EMSI_IIR packet, the negotiation is cancelled, and should not proceed further. This usually means that one side or the other feels the packets have a slim chance of making it to the other error-free. Since this packet never changes, it is always "**EMSI_IIR61E2." Also, the EMSI_ACK and EMSI_NAK packets should be noted. They are "**EMSI_ACKA490" and "**EMSI_NAKEEC3" respectively. In addition, every packet in the IEMSI negotiation ends with an ASCII 13 (dec) character - better known as the CR, or carriage return. ─=End of IEMSI.DOC=─